Examples of API Use

This POST call is used to create or update a single employer record. The way this call is structured is appropriate for single-record posts ONLY. If you want to update multiple records, you must add the <FIRM> tag to this call as the next level after the <LxERP> tag, before the object tags—which, in this case, is the <Employer> tag.

Method: POST

URL: {{url}}/rest/businessObject

Raw XML Input:

<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
    <Employer clientID="EMP_12345‐SITE" match="clientID">
        <EmployerName>Acme Co</EmployerName>
    </Employer>
</LxERP>

XML Response:

In the XML response below, you can see that the employer record was successfully created. The "create='true'" and "update='false'" attributes tell us that this is not an update to an existing record. When a new record is created in Lucernex, it is automatically assigned a unique LxID. This LxID can be used in future API calls to uniquely identify the record for updates.

<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
    <success create="true" delete="false" update="false" clientID="EMP_12345‐SITE" lxID="699209"
        objectType="Employer"/>
</results>

The following POST call is used to create or update multiple employer records. The way this call is structured can be used for either single-record or multiple-record updates.

Notes:

• The synchronous parameter is “false” by default. We only recommend an asynchronous call if the content will take more than 5 minutes to process (such as files larger than a few 100 MB).

• The fields being created may differ from object to object.

Method: POST

URL:

This URL is used for file-based updates:

{{url}}/rest/firm?synchronous=true

This URL is used for non-file-based updates:

{{url}}/rest/businessObject?allowUpdate=true

XML File Content:

<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
    <Firm>
        <Employers>
            <Employer clientID="EMP_Employer1" match="clientID">
                <EmployerName>Employer1</EmployerName>
            </Employer>
            <Employer clientID="EMP_Employer2" match="clientID">
                <EmployerName>Employer2</EmployerName>
            </Employer>
        </Employers>
    </Firm>
</LxERP>

XML Response:

In the XML response below, you can see that the employer records were successfully created. The "create='true'" and "update='false'" attributes tell us that these were not updates to existing records. When a new record is created in Lucernex, it is automatically assigned a unique LxID. This LxID can be used in future API calls to uniquely identify the record for updates.

<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
    <success create="true" delete="false" update="false" clientID="EMP_Employer1" lxID="723002“
        objectType="Employer"/>
    <success create="true" delete="false" update="false" clientID="EMP_Employer2" lxID="722995“
        objectType="Employer"/>
</results>

You can create many types of records in Lucernex, and not all fields are required. Refer to the View Object Model page to learn which fields are required for the type of object you are creating.

Below is an example of recommended fields when creating an Employer record.

<Employer clientID="EMP_12345‐SITE" match="clientID">
    <EmployerName>Acme Co</EmployerName>
    <APVendorNumber>12345‐SITE</APVendorNumber>
    <CompanyType>Vendor</CompanyType>
    <CodeContactTypeIDList>Payee</CodeContactTypeIDList>
    <Phone>555‐555‐5555</Phone>
    <StreetAddress1>12 Main St</StreetAddress1>
    <City>San Diego</City>
    <IStateProvinceCountryID>
        <State>CA</State>
        <Country>United States</Country>
    </IStateProvinceCountryID>
    <PostalCode>92104</PostalCode>
</Employer>

This GET call retrieves a list of the employers which exist in your firm. Each employer record is returned with the business object link, the object type, the employer name, and the LxID.

This call may not be appropriate if you have a large number of employers in your firm. If you want to get information for a specific employer, you may want to try a FIQL query. FIQL queries will allow you to filter and more directly target the employer information you are looking for.

Method: GET

URL: {{url}}/rest/businessObject/Employer

XML Response:

<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<businessObjectLinks>
    <businessObjectLink href="https://train.lucernex.com/rest/businessObject/Employer/699209"
        objectType="Employer" name="Acme Co" lxID="699209"/>
...
...
</businessObjectLinks>

This GET call retrieves information about a specific employer by using the Client ID field as an identifier. This call should return all global fields, but you may find that some firm-specific fields may not be returned.

Method: GET

URLs:

• {{url}}/rest/businessObject/Employer/clientid/12345‐SITE

• {{url}}/rest/businessObject/Employer/12345‐SITE

XML Response:

<?xml version="1.0" encoding="UTF‐8"?>
<Employer href=https://train.lucernex.com/rest/businessObject/Employer/lxid/699209 clientID="12345‐SITE">
    <City>San Diego</City>
    <CodeContactTypeIDList>
        <CodeContactTypeID clientID="client‐8055‐1497641023714">Payee</CodeContactTypeID>
    </CodeContactTypeIDList>
    <CompanyType>Vendor</CompanyType>
    <EmployerName>Acme Co</EmployerName>
    <HasAfterHoursSupport>false</HasAfterHoursSupport>
    …

This GET call retrieves information about a specific employer by using the LxID field as an identifier. This call should return all global fields, but you may find that some firm-specific fields may not be returned.

Method: GET

URLs:

• {{url}}/rest/businessObject/Employer/lxid/699209

• {{url}}/rest/businessObject/Employer/699209

XML Response:

<?xml version="1.0" encoding="UTF‐8"?>
<Employer href=https://train.lucernex.com/rest/businessObject/Employer/lxid/699209 clientID="12345‐SITE">
    <City>San Diego</City>
    <CodeContactTypeIDList>
        <CodeContactTypeID clientID="client‐8055‐1497641023714">Payee</CodeContactTypeID>
    </CodeContactTypeIDList>
    <CompanyType>Vendor</CompanyType>
    <EmployerName>Acme Co</EmployerName>
    …

This GET FIQL query gets an employer record where the Employer Name equals Acme Co, and includes the Employee Name field and the AP Vendor Number field. Learn more about FIQL parameters, comparison editors, logical operators, reserved words, and query options.

fiql=ge={today's date};=lt={tomorrow's date}

Method: GET

URL: {{url}}/rest/businessObject/Employer/details?fiql=EmployerName==Acme%20Co&fields=EmployerName,APVendorNumber

XML Response:

<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
    <Employer lxID="699209">
        <EmployerName>Acme Co</EmployerName>
        <APVendorNumber>12345‐SITE</APVendorNumber>
    </Employer>
</LxERP>

If you need to get a large amount of data from the system, and do not want to create an API call, you can use the Report Builder to create a custom XML report and then use a GET call to run the report and retrieve the data. The benefit of this method is that you can reduce the number of fields referenced in your call, and use the filtering capabilities of FIQL.

• Create a report with the XML View Type.

  To avoid having to manually removing spaces from every field, save your report as an XML report before adding any of your fields. Then, the Report Builder will automatically remove the spaces for you when you add fields.

• Fields and field labels must be XML tag-compatible, meaning they cannot have spaces or any of the reserved characters.

• Add Label Fields as the first and last columns of the layout. These label fields should have the same text, and are used to tell you where one record begins and the other ends.

• Learn more about creating reports by reviewing our Reporting Walkthroughs.

Method: GET

URL: {{url}}/rest/businessObject/RunReport/details?fiql=ReportID==Report Name[additionalFIQL]

• Report Name is the name of the report to be run. Avoid special characters in the report name.

• [additionalFIQL] is any additional FIQL criteria needed to restrict results.

XML Response:

This call will return the contents of your XML report.

You can get user permissions for scheduled tasks so that when developing a user interface, you can omit an Edit Task option when the user does not have permissions to do so. You can get the user permissions for scheduled tasks with this HTTP Request Method:

GET …/rest/scheduletask/securityaccess?projectEntityID=[projectEntityID]

Response:

A list of tasks that indicates whether they are editable for the user. When the user has no access, the response is No Access. When the user has view access, the response includes the taskName, taskId and editable is false. When the user has edit access, the response includes the taskName, taskId and editable is true.

For example:

[ { "editable": true, "taskName": "Group 1", "taskId": 5404774 }, { "editable": true, "taskName": "Task 1", "taskId": 5404775 }, { "editable": true, "taskName": "Group 2", "taskId": 5404776 }, { "editable": true, "taskName": "Task 3", "taskId": 5404777 }, { "editable": false, "taskName": "Task 2", "taskId": 5404778 } ]

In this example, all tasks except taskId: 5404778 are editable.

This PUT call updates an existing Employer record where the Client ID field is equal to EMP_12345‐SITE. The match="clientID" XML attribute is required when updating Employer records, but is not required for other types of records.

You may choose to do a PUT query in the scenario where you only want to update records, rather than allowing the system to create a record if one doesn't exist. This helps prevent the accidental creation of unwanted data.

Method: PUT

URL: {{url}}/rest/businessObject

Raw XML Input:

<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
    <Employer clientID="EMP_12345‐SITE" match="clientID">
        <StreetAddress1>555 Broadway</StreetAddress1>
    </Employer>
</LxERP>

XML Response:

<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
    <success create="false" delete="false" update="true" clientID="EMP_12345‐SITE" lxID="699209"
        objectType="Employer"/>
</results>

This POST call updates an existing Employer record where the Client ID field is equal to EMP_12345‐SITE. The match="clientID" XML attribute is required when updating Employer records, but is not required for other types of records.

The difference between this POST call and the above PUT call is that while PUT prevents the accidental creation of data, POST will create a new record if the referenced record does not exist. Use caution with POST calls to prevent unintended record creation.

Method: POST

URL: {{url}}/rest/businessObject/?allowUpdate=true

Raw XML Input:

<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
    <Employer clientID="EMP_12345‐SITE" match="clientID">
        <StreetAddress1>16 Fifth Avenue</StreetAddress1>
    </Employer>
</LxERP>

XML Response:

<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
    <success create="false" delete="false" update="true" clientID="EMP_12345‐SITE" lxID="699209"
        objectType="Employer"/>
</results>

This POST call updates multiple Employer records.

Notes:

• The synchronous parameter is “false” by default. We only recommend an asynchronous call if the content will take more than 5 minutes to process (such as files larger than a few 100 MB).

• If an object does not exist, it will be created.

• The fields being created may differ from object to object.

Method: POST

URL: {{url}}/rest/firm?synchronous=true

XML File Content:

<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
    <Firm>
        <Employers>
            <Employer clientID="EMP_Employer1" match="clientID">
                <StreetAddress1>12 Main St</StreetAddress1>
            </Employer>
            <Employer clientID="EMP_Employer2" match="clientID">
                <Inactive>true</Inactive>
            </Employer>
        </Employers>
    </Firm>
</LxERP>

XML Response:

In the XML response below, you can see that the employer records were successfully updated. The "create='false'", "delete='false'", and "update='true'" attributes tell us that these were updates to existing records.

<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
    <success create="false" delete="false" update="true" clientID="EMP_Employer1" lxID="723002“
        objectType="Employer"/>
    <success create="false" delete="false" update="true" clientID="EMP_Employer2" lxID="722995“
        objectType="Employer"/>
</results>

This DELETE call removes a single employer record where the clientID is equal to EMP_12345‐SITE. There is no "undo" for a DELETE call, so ensure that you are deleting the correct record before you make the call.

There are some database tables—such as the SLSummary and SLPeriod tables, which are used for accounting schedules—that do not allow DELETE calls.

Method: DELETE

URLs:

• {{url}}/rest/businessObject/Employer/EMP_12345‐SITE

• {{url}}/rest/businessObject/Employer/699209

XML Response:

<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
    <success create="false" delete="true" update="false" clientID="EMP_12345‐SITE" lxID="699209"
        objectType="Employer"/>
</results>